Squeeze2Raop – AirPlay bridge - User Guide
This program (squeeze2raop - sq2r for short) allows AirPlay compatible devices to be used and controlled from LMS as regular squeezebox devices. It scans the local network for renderers and creates an instance of an LMS software player for each player found.
It can run on any computer running Windows or Linux x86. OSX and Linux ARM versions may also be available. For speed reasons, it is better to be co-located with LMS, but this is not essential, it can run on any computer connected to LMS via Ethernet or WiFi.
What version to select: Linux platforms have a normal version and a –static version. The –static version removes the dependency with all shared libraries. It’s convenient on some NAS platform that often are not full Linux systems, but the drawback is that libraries updates provided with your system will be not be usable by sq2r.
Sq2r receives commands and audio streams from LMS. These are transformed into AirPlay commands and streams, will all necessary decoding / resampling.
Gapless, Replay Gain, Fading and Synchronization are fully supported
README
Volume management: By default, LMS commands are translated into AirPlay commands using device’s volume control (‘hardware’ mode). Any change made using the device remote control is also fed back to LMS. Some players have faulty volume control that stops playback for a few seconds at each command. To avoid this, a software gain can be applied by sq2r on digital samples (in that case, feedback is disabled). It might be needed to adjust the correspondence between AirPlay volumes( –30…0) and LMS volume (1..100). It’s also possible to block all LMS volume commands, set an initial AirPlay volume level and disable feedback. See volume parameters below for more details.
Format supported: AirPlay requires tracks to be 44.1kHz/16 bits, sq2r will do the necessary decoding. It supports mp3,flac,aac,aif,pcm as well as resampling and 24 bits truncating. Such decoding requires a fair amount of CPU. You need to have the corresponding libraries installed. For windows, the DLL are provided in the package, for Linux you need to make sure that the .so are installed. (libFLAC.so.8, libmad.so.0 and/or libmpg123.so.0, libfaad.so.2). The resampler is always built-in with the application, no need of shared librairies. For OSX, as such libraries seems to be difficult to find, everything is built-in. The –static version of Linux have the codec libraries built-in.
Co-existence with other controllers: When playing, sq2r takes the exclusive usage of the AirPlay device and will keep it even while the player is stopped or paused. The parameter <idle_timeout> configures the amount of seconds after which sq2r will release the AirPlay device, once it has been stopped or paused. The release does not happen immediately after pause or stop because some players can take multiple seconds to establish the connection, and this is very annoying when pausing for a short period of time or when moving between tracks. Note that most players disconnect anyway after ~30s receiving no audio. Starting with version 0.2, sq2r supports the DACP protocol, so any AirPlay remote controller will work and ‘control’ LMS. On network AV amplifiers, when switching source directly on the player, sq2r will gracefully give back control of the device and automatically stop LMS
Synchronization: There is a normally no need to adjust your player delay in LMS player settings (not in the plugin settings). Still, it might be needed to add 25-50ms of player latency in a few cases.
Network bandwidth and CPU: Audio is sent in raw PCM which requires 1.4Mbits/s per player (plus some overhead), so this puts a fair amount of constraints on your network and CPU but I’ve made some tests with flac or mp3 decoding running on 3 players on a raspberry Pi 2, only connect using WiFi and it consumes less than 20%. Starting with version 0.2.2.0, audio can be re-encoded using ALAC. This saves 30~50% network bandwidth but adds a few percent more of CPU per player.
Players detection: If you have more than one Ethernet interface and AirPlay devices detection does work, use the <interface> parameter (Network Interface in LMS user interface) to force the IP address of the machine running sq2r. When used on the same machine than LMS, the interface can be given automatically (see plugin settings in LMS).
Stability: It still happens that some players get disconnected. There is a watchdog mechanism that (normally) re-establish the connection after ~30s, so wait a bit if it happens, don’t stop LMS or stop the playback. In case nothing comes back, you can toggle off/on the player in LMS, it does a full reset of sq2r for that player
Firewall: The firewall must let sq2r open various ports (3 UDP and 1 TCP). In Windows, just create a new rule for c:\programdata\squeezecenter\cache\installedplugins\plugins\raopbridge\bin\squeeze2raop-win.exe in the firewall
Garbled sound: Reduce the “Networking Buffer” (<read_ahead> parameter) in the plugin parameters to a value below 3000.
No sound after 30~90 seconds: It has been observed, at least on AppleTV, that if metadata sending is disabled, the player closes the connection avec 30 to 90 seconds, resulting a muted output, although everything looks fine from LMS. Just enable metadata sending to make sure the plugin regularly communicates control information with the player
AppleTV: Starting with iOS 10.2, AppleTV requires a pairing with any client that wants to send audio using AirPlay. Version 0.3.0.0 and above supports this but you need a LMS web UI. In the plugin settings, you’ll see a “Pair” button next to any detected AppleTV. Click there, look at the code displayed on your TV, enter that code and click “Submit”. If pairing is successful, A long line should appear to the right of the “Pair” button. If no “Pair” button appear, make sure you’ve activated the bridge, waited 30sec and refreshed the setting page. If you don’t use the LMS web UI, send me an email and I’ll provide a small Perl script that makes the pairing.
The simplest way to use sq2r is to install the “AirPlay bridge” plugin on the system running LMS. If this is not practical and you need to install it on another computer, see Section 3 below.
i. Go to the Settings, Plugins page on the LMS GUI.
ii. Go to 'Additional Repositories' near the bottom. If this is not available, there should be an option to enable third party plugins. Tick this, and press 'Apply' at bottom right.
iii. Add the following line to the list of additional repositories:
development version: http://downloads.sourceforge.net/project/lms-to-raop/dev/repo-sf.xml
stable version: http://downloads.sourceforge.net/project/lms-plugins-philippe44/repo-sf.xml
Restart LMS.
iv. You should now find that there is a new section listing the AirPlay plugin Tick this to make it available on the next LMS restart, and restart LMS.
v. Go to the Settings, Advanced page on the LMS GUI and select the AirPlay bridge entry.
vi. Turn on all your AirPlay devices.
Tick the ’Start the Bridge’ tickbox, choose the executable for your platform if more than one is available and tick ‘Apply’ at the right-bottom of the page. As the ‘autosave’ option is ticked by default, a configuration will be generated automatically after ~30s, just wait and refresh the page to see it. You can optionally force configuration file generation by ticking ‘Generate’ (not recommended)
From that point, you might be lucky and have sq2r and your players working with all built-in defaults
vii. Make sure the ‘Start the Bridge’ tickbox is unticked
viii. Edit the parameters if you need to (you can, for example, change the name of the player).
ix. Save these values and restart the plugin by ticking the 'Start the Bridge' tickbox and press 'Apply'.
x. The parameters on the plugin settings screen include most of those in the configuration file. See Section 5 for details of each configuration file parameter. You can edit the configuration file manually if you really need to.
xi. If you get stuck, read Section 4 which may help you to choose different options.
When ‘autosave’ is ticked, the configuration will be saved with an updated list of players at each network scan (see scanning option to change period). It is also possible to manually update your configuration file at any time by ticking ‘Generate’ (whether ‘Start the Bridge’ is ticked or not).
By default sq2r supports pcm, aif, mp3,flc and aac. You can change (restrict, not add others) this using the <codec> parameter in the configuration file (see below) and choose to have LMS do some transcoding instead
Within a short time after restarting the plugin the renderers will appear as renderers in the LMS GUI and you should be able to play tracks as normal with any squeezebox device (or squeezelite, squeezeplay etc.).
You can copy the squeeze2raop program from http://sourceforge.net/projects/lms-to-raop/files to the location where you want to run it.
On Windows, you need to copy pthreadBC2, cc32160mt.dll, libeay32.dll, ssleay32.dll to the same directory as the program.
On Linux (Intel CPU), if you use a 32 bit system, just copy squeeze2raop-x86. If your system is 64bits, you need to either have libc6 32 bits or choose the native 64 bits version squeeze2raop-x86-64. To install it such 32 bits libraries on a 64 bits systems, do at any command prompt
sudo apt-get install libc6:i386:
If you are familiar with compiling programs on your platform, go to https://github.com/philippe44/LMS-to-Raop/tree/master/stable where the stable version of the source of the program is located. The source can be downloaded and built in the normal way. The README contains compilation instructions.
Follow these steps:
-or- (preferred method)
In the directory containing sq2r you should now have a file called config.xml. This lists all the renderers found by sq2r and contains the default configuration values. Take a copy of this file and save it somewhere. It may come in useful some day.
If you ever add a new renderer to your system you will need to repeat this process, unless you have launched sq2r with the “-I <config file> in which case newly found players are automatically added. If you 'save' again to your current configuration file your existing options will be carried over and newly discovered player will be added.
The configuration file you now have (config.xml) consists of a general header, some common parameters, and then a section for each and every renderer sq2r has found.
To see the command line switches, run squeeze2raop with -h. Some of these options, such as the server id, can be overridden in the configuration file.
You have a choice as to where to place logs and where the configuration file is located.
On startup, sq2r tries to open a file named “config.xml” in the current directory (or uses the filename provided using the –x option). If no file is found, all parameters will be set to default. To generate such a configuration file, type “save <filename>” when sq2r is running and a file with all existing configuration parameters and discovered devices will be created. Alternatively, you can launch sq2r with the “-i <config file>” option.
Type ‘squeeze2raop-[you platform] –h” for a list of command line options
There a few commands that can be entered on the command line while sq2r is running, unless you have launched it with the “-Z” option:
· exit : terminates
· save <filename> : save the config file
· stop * or stop <string> will stop any renderer whose name matches <string>
Searches for new (or enabled but not yet running) AirPlay devices will occur at a configurable interval and for a configurable amount of time. The first search will last 15 seconds before LMS devices are created.
If a renderer disappears from the LAN, it will be automatically removed after a configurable number of failed searches (see <remove_count> parameter below)
You can do play, pause, stop, mute and volume control, skip to next and previous tracks. Fast forward / rewind works but is not very convenient. It does increment time by 10s chunks.
Because they receive audio frame in real time, there is a need for players to buffer a certain amount of ms of audio ahead. This can bet set in <read_ahead> parameter. Note that when using software-volume (<player_volume> set to a positive value) a delay of <read_ahead> ms will happen between the volume change request and the actual change.
The full set of options is as follows (comments are shown in italics and do not appear in the file). A number of parameters are there for future use only, and commented N/A (Not Applicable).
There are 3 parts in a configuration file: system parameters, <common> parameters that apply by default to all AirPlay devices and, for each individual AirPlay renderer discovered, a <device> section. When a parameter is set in an AirPlay renderer <device> section, it takes precedence (but only for that renderer) over the same parameter in the <common> section.
<?xml version="1.0"?>
<squeeze2raopt>
Global options
<interface>[ip] | ?]</interface> default = ?
ip = IP address of the interface that should be use. This is only useful for a computer with multiple Ethernet interface or to improve player detection using mDNS protocol
Use ? for auto selection
<scan_interval>[0 | value]</scan_interval> default and forced minimum= 120
Sets how often (in seconds) a network scan is done to update AirPlay media renders list (and add or remove corresponding LMS players). 0 disables rescan (only one scan upon startup)
<scan_timeout>[ value]</scan_timeout> default and forced minimum = 15
Sets how long (in seconds) lasts a network rescan for Airplay media renderer. It is forced to a minimum of 15 and a maximum of <scan_interval> - 15.Note that the *first* scan is always 15s
<exclude_model>[model1;model2…modelN]</exclude_model> default = “aircast;airupnp”
A list of model name tp be excluded from the search. Any device containing one of these strings will be discarded. Note that this parameter is not created when default config file (-i) is generated.
<log_limit>[-1 | value]</log_limit> default = -1
Sets the maximum size (in MB) of a logfile. Set to -1 for unlimited
<slimproto_log>[error | warn | info | debug | sdebug]</slimproto_log>
<stream_log>[error | warn | info | debug | sdebug]</stream_log>
<output_log>[error | warn | info | debug | sdebug]</output_log>
<decode_log>[error | warn | info | debug | sdebug]</decode_log>
<raop_log>[error | warn | info | debug | sdebug]</raop_log>
<util_log>[error | warn | info | debug | sdebug]</util_log>
<main_log>[error | warn | info | debug | sdebug]</main_log>
<slimmain_log>[error | warn | info | debug | sdebug]</slimmain_log>
Level of debugging for each sub-item of sq2r. Leave these at info in the current version.
These can be overridden in the command line with the -d option.
<common>
All items in this sub-section set the default behaviour for all renderers. Any option can be repeated in the <device> section of a given renderer to override the <common> option.
<server>[ip[:port] | ?]</server> default = ?
ip = IP address or network name, port = port number (usually 3483) of your LMS server.
Use ? for auto-discovery
This can be overridden in the command line with the -s option.
<enabled>[0 | 1]</enabled> default = 1
‘1’ to automatically add any discovered AirPlay renderer to LMS players, even if there is no <device> section referring to it. '0' to prevent this.
<remove_count>[0 | value]</remove_count> default = 60
Set how many times a device must be missing a mDNS rescan before it is removed from the list. Set to 0 to disable removal. Note that if the device continues to respond to ‘keepalive’ packets, it will not be removed, regardless of this parameter
<streambuf_size>[value > 1000000]</streambuf_size> default = 2457600
Size of the internal memory buffer used to store audio data sent by LMS. Any value above 1,000,000 is fine. If your network is slow you may need to increase it.
<output_size>[value > 1000000]</output_size> default = 2457600
Size of the internal memory buffer used to store audio data sent by LMS. Any value above 1,000,000 is fine. If your network is slow you may need to increase it.
<player_volume>[ -1 | 0..100]<player_volume > default =-1
Defines the volume level that is set by sq2r every times it (re)connects to the AirPlay device. Set it to -1 to disable setting a volume.
<volume_mode>[ 0 | 1 | 2]</volume_mode > default =2
Defines how LMS volume commands are forwarded to the AirPlay device.
0: disable forwarding. LMS volume has no impact on player.
1: use ‘ software’ volume where the gain is applied by sq2r directly on the digital samples. This is needed for players that do not handle not handle properly volume commands, so
2: use AirPlay device native volume control(hardware).
<mute_on_pause>[ 0 | 1]</mute_on_pause > default =1
LMS default’s behaviour is to mute a player when paused. Some AirPlay devices (not Apple native ones) ignore LMS volume command upon resume and stay muted until a manual volume change is made in LMS. Set this to 0 to block LMS mute command when AirPlay device is paused
<volume_trigger >[ 0 | 1]</volume_trigger > default =0
Some AirPlay devices ignore volume command until they have sent (feedback) their current volume to their controller. As a result, they can stay muted upon resume after a long pause (above 30s). Set this parameter to wait for such feedback to be received by the bridge before sending any volume command. This is required for Yamaha WX serie
<prevent_playback >[stop | off]</prevent_playback > default =stop
When an AirPlay device (e.g. an AV receiver) is switched to another source using its remote, the bridge is notified and must prevent LMS from trying to continue handling that device. It’s possible to either stop current track (it will stop all other players that are synchronized) or to power off only the associated virtual LMS player, letting the other LMS devices continue playing.
<volume_feedback>[0 | 1]</volume_feedback > default =1
Defines how AirPlay volume changes made locally on the player are feedback to LMS
0: disable feedback
1: AirPlay changes are forwarded to LMS
<volume_mapping>[string]</volume_mapping > default = -30 :1, -15 :50, 0:100
This parameter maps the volume values between AirPlay and LMS. AirPlay volume goes from -30.0 to 0.0 (loudest) and is decimal while LMS volume goes from 1 to 100 and is integer. Unfortunately, some players do not make a straight ‘linear’ conversion like LMS = (AirPlay/30+1)*100. Typically, a value of 50 on LMS scale instead of being -15 is -17.625. This is a problem for remote volume feedback as the value set by the AirPlay device does not “match” the value estimated by LMS. This parameter allows sq2r to compute a closer matching between the two by providing a few reference points that are used to do the full translation between the volumes. This parameter is in a format of “a1:b1, a2:b2, …an:bn” where “a” is an AirPlay volume value and “b“is the LMS corresponding value. It’s possible to set as many points as 100 (full match), but when less are provided (which is the normal case, typically 5 points are more than enough), sq2r does the interpolation between the two closest points. Note that LMS volume of ‘0’ corresponds to AirPlay level of ‘-144.0’ and shall *not* be set as a reference point. The default value is a linear match
<idle_timeout>[value > 10]</idle_timeout> default = 30
In AirPlay systems, a controller requires exclusive control of the player and must open a session for this. This session creation can take up to 10s on some players, so even when stopped or paused, sq2u will keep the session alive. The session an be terminated by switching off the player in LMS, but this can still be inconvenien. Set this to a value above 10 (in seconds) to set the time after what, when paused or stopped, the session will be disconnected. When resuming play, it will be automatically reopened, but it might take time.
<encryption>[0 | 1]</encryption> default = 0
Set it to 1 to force encryption on players that support it. Seems necessary for ShairportW. As it uses more CPU for no benefits, it is strongly recommended to disable it
<credentials>[string@ip:port]</credentials> default = 0
This is the credentials needed for an AppleTV to accept audio. Do not modify this. It shall be generated using LMS web UI. If you can’t use it, send me an email and I’ll provide you with a small Perl snippet that does pairing
<alac_encode>[0 | 1]</alac_encode> default = 0
Set it to 1 to encode audio using ALAC. This reduces network usage by 2 (average ALAC ratio) but consumes much more CPU for the re-encoding process. Otherwise, audio is sent at raw PCM (1411 kbps)
<read_ahead>[value > 200]</read_ahead> default = 3000
AirPlay devices use a Realtime Transport Protocol (RTP) to send audio data (basically they just and ethernet wire).To avoid playback interruption, enough data must be buffered to absorb network throughput jitter. Do not set too much buffering or an overrun might happen and sound will be garbled. For example Apple TV 1 requires a value of around 1000. This parameter sets the number of ms of buffer in theplayer. Note that due to technical limitations, when pause/unpause, player will restart <read_ahead> ms after the paused value. This does not affect synchronization, though.
<sample_rate>[0 | 1]</sample_rate> default = 96000
The maximum sample rate supported by sq2r, as reported to LMS. LMS will refuse to play a track above that rate (and does not do transcoding by default). Note that this is not the rate of the AirPlay device for which all tracks are converted to 44.1kHz by sq2r for AirPlay compliance
<resample>[0 | 1]</resample> default = 1
Set this to 0 to disable resampling that adjusts sample rate to 44.1kHz. You might want to do that if resampling consumes too much CPU, you won’t be able to listen to any track other than 44.1kHz though (except for mp3 tracks if you use mpg123codec instead of mad as it does directly a basic resampling)
<resample_options>[string]</resample_options> default = empty
Used to tweak the resampling parameters. See libsox and squeezelite options. MORE DETAILS LATER
<send_metadata>[0 | 1]</send_metadata> default = 1
If you do not want to see metadata (Artist, Album name etc.) on your renderer, or if you have a login and password for the LMS CLI interface, set this to 0.
<send_coverart>[0 | 1]</send_coverart> default = 1
If you do not want to see coverert on your renderer, or if you have a login and password for the LMS CLI interface, set this to 0.
<auto_play>[0 | 1]</auto_play> default = 0
Set to 1 if you want the player to auto start playing on power on. Seems that this feature is broken in LMS, so this is a workaround.
</common>
This is the beginning of the sections that describes each device. There must be one <device> section for each AirPlay renderer. Any parameter set in the <common> can be repeated here, to override the what was set on the <common> section.
first device …
<device>
<udn>9C645E0296F5@JBL OnBeat Air0296F5._raop._tcp.local </udn>
!!! DO NOT EDIT THIS !!! It is the AirPlay device unique identifier for that renderer – this is discovered automatically.
<friendly_name>AirPort-Express<friendly_name>
!!! DO NOT EDIT THIS !!! It is the UPnP device name set by renderer – this is discovered automatically. The example is for a AirPort Express.
<name>[string]</name>
The name of the renderer as seen in LMS – can be set to whatever you want, from the LMS web interface or from the plugin’s settings. Defaults to the AirPlayt built-in name.
<mac>[xx:xx:xx:xx:xx:xx]</mac>
The mac address of the player, note that all players must have unique mac for LMS to work properly. If this parameter is omitted, sq2r will try to discover the true physical address and replace the first 2 bytes with ‘aa’(this is needed to make sure mac is unique across different bridge plugins). If it cannot be discovered, then a random unique value will be generated, again with the first 2 bytes set to ‘bb’
<enabled>[0 | 1]</enabled> default = 1
Set to 1 to allow the AirPlay renderer to be managed be sq2r. An LMS device will be created for each renderer whose mode is above 0. Set to 0 to ignore the renderer. It may be better to keep a list of all known renderers in the configuration and disable those you don't want to use, so that you have a list of the uuids should you ever need them.
</device>
next device …
<device>
…
</device>
</squeeze2raop>
<?xml version="1.0"?>
<squeeze2raop>
<interface>?</interface>
<slimproto_log>info</slimproto_log>
<stream_log>warn</stream_log>
<output_log>info</output_log>
<decode_log>warn</decode_log>
<main_log>info</main_log>
<slimmain_log>info</slimmain_log>
<raop_log>info</raop_log>
<util_log>info</util_log>
<scan_interval>30</scan_interval>
<scan_timeout>15</scan_timeout>
<log_limit>-1</log_limit>
<common>
<streambuf_size>2097152</streambuf_size>
<output_size>1764000</output_size>
<enabled>1</enabled>
<codecs>flc,pcm,aif,aac,mp3</codecs>
<sample_rate>96000</sample_rate>
<resample>1</resample>
<resample_options></resample_options>
<send_metadata>0</send_metadata>
<send_coverart>0</send_coverart>
<remove_count>30</remove_count>
<auto_play>0</auto_play>
<idle_timeout>30</idle_timeout>
<encryption>0</encryption>
<alac_encode>0</alac_encode>
<read_ahead>1500</read_ahead>
<server>?</server>
<player_volume>-1</player_volume>
<volume_feedback>1</volume_feedback>
<volume_mode>2</volume_mode>
<volume_mapping>-30:1, -15:50, 0:100</volume_mapping>
<mute_on_pause>1</mute_on_pause>
<volume_trigger>0</volume_trigger>
</common>
<device>
<udn>000678110596@marantz NR1603._raop._tcp.local</udn>
<name>Marantz-NR1603 (airplay)</name>
<friendly_name>marantz-NR1603</friendly_name>
<enabled>1</enabled>
<send_metadata>1</send_metadata>
<send_coverart>1</send_coverart>
<server>192.168.2.10</server>
<volume_mapping>-30:1, -25.125:20, -20.125:40, -17.625:50, -10.5:60, -3:70, 0:80, 0:100</volume_mapping>
<credentials>124569890809767564654564ABC7D6@192.179.0.1:7000</credentials>
</device>
</squeeze2raop>